---
layout: api
page_title: PKI - Secrets Engines - Issuance Protocols
description: This is the API documentation for the issuance protocol support in Vault PKI.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Standard Issuance Protocols (API)

- [ACME Certificate Issuance](#acme-certificate-issuance)
  - [ACME Directories](#acme-directories)
  - [Get ACME EAB Binding Token](#get-acme-eab-binding-token)
  - [List Unused ACME EAB Binding Tokens](#list-unused-acme-eab-binding-tokens)
  - [Delete Unused ACME EAB Binding Tokens](#delete-unused-acme-eab-binding-tokens)
  - [Get ACME Configuration](#get-acme-configuration)
  - [Set ACME Configuration](#set-acme-configuration)
  - [List ACME Account Keys](#list-acme-account-keys)
  - [Get ACME Account Info](#get-acme-account-info)
  - [Update ACME Account Info](#update-acme-account-info)
- [EST - Certificate Issuance <EnterpriseAlert inline="true" />](#est-certificate-issuance)
  - [EST Protocol Paths <EnterpriseAlert inline="true" />](#est-protocol-paths)
  - [Read EST Configuration <EnterpriseAlert inline="true" />](#read-est-configuration)
  - [Set EST Configuration <EnterpriseAlert inline="true" />](#set-est-configuration)
- [CMPv2 - Certificate Management Protocol (v2) <EnterpriseAlert inline="true"/>](#cmpv2-certificate-issuance)
  - [CMPv2 Protocol Paths <EnterpriseAlert inline="true" />](#cmpv2-protocol-paths)
  - [Read CMPv2 Configuration <EnterpriseAlert inline="true" />](#read-cmpv2-configuration)
  - [Set CMPv2 Configuration <EnterpriseAlert inline="true" />](#set-cmpv2-configuration)
- [SCEP - Simple Certificate Enrollment Protocol <EnterpriseAlert inline="true" />](#scep-certificate-issuance)
  - [SCEP Protocol Paths <EnterpriseAlert inline="true" />](#scep-protocol-paths)
  - [Read SCEP Configuration <EnterpriseAlert inline="true" />](#read-scep-configuration)
  - [Set SCEP Configuration <EnterpriseAlert inline="true" />](#set-scep-configuration)

## ACME certificate issuance

Starting with Vault 1.14, Vault supports the [ACME certificate lifecycle
management protocol](https://datatracker.ietf.org/doc/html/rfc8555) for issuing
and renewing leaf server certificates.

In order to use ACME, a [cluster path](#set-cluster-configuration) must be
set and ACME must be [enabled in its configuration](#set-acme-configuration)
with the [required headers](#acme-required-headers) enabled on the mount
tuning.

Using ACME with a role requires `no_store=false` to be set on the role; this
allows the certificate to be stored and later fetched through the ACME
protocol.

### ACME directories

Vault PKI supports the following ACME directories, providing different
restrictions around usage (defaults, a specific issuer and/or a specific
role). To interact with these directories, specify the directory URL in
an ACME client. For example, with the EFF's [CertBot](https://certbot.eff.org/):

```
$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ...
```

These endpoints are unauthenticated from a Vault authentication model, but
internally authenticated via the ACME protocol.

| Method | Path                                                               | Default Directory Policy   | Issuer                | Role          |
|:-------|:-------------------------------------------------------------------|:---------------------------|:----------------------|:--------------|
| `ACME` | `/pki/acme/directory`                                              | `sign-verbatim`            | `default`             | Sign-Verbatim |
| `ACME` | `/pki/acme/directory`                                              | `role:role_ref`            | Specified by the role | `:role_ref`   |
| `ACME` | `/pki/acme/directory`                                              | `external-policy(:policy)` | Specified by CIEPS    | CIEPS         |
| `ACME` | `/pki/issuer/:issuer_ref/acme/directory`                           | `sign-verbatim`            | `:issuer_ref`         | Sign-Verbatim |
| `ACME` | `/pki/issuer/:issuer_ref/acme/directory`                           | `role:role_ref`            | `:issuer_ref`         | `:role_ref`   |
| `ACME` | `/pki/roles/:role/acme/directory`                                  | (any)                      | Specified by the role | `:role`       |
| `ACME` | `/pki/issuer/:issuer_ref/roles/:role/acme/directory`               | (any)                      | `:issuer_ref`         | `:role`       |
| `ACME` | `/pki/external-policy(/:policy)/acme/directory`                    | (any)                      | Specified by CIEPS    | CIEPS         |
| `ACME` | `/pki/issuer/:issuer_ref/external-policy(/:policy)/acme/directory` | (any)                      | Specified by CIEPS    | CIEPS         |

When a role is not explicitly specified, behavior is specified by the
`default_directory_policy` in the [ACME configuration](#set-acme-configuration).
These directories can also be forbidden by setting that policy as `forbid`.  If
the policy is `sign-verbatim` then _any_ identifier for which the client can
prove ownership of will be issued for.  This is similar to using the
[Sign Verbatim](#sign-verbatim) endpoint, but with additional verification
that the client has proven ownership (within the ACME protocol) of the
requested certificate identifiers. When `external-policy` is specified as the
default value, the Certificate Issuance External
Policy Service (CIEPS)<EnterpriseAlert inline="true" /> is used for
validating and templating the certificate instead of a role; ACME's challenge
validation is still enforced. An optional policy name can be specified by using
`external-policy:policy`. Roles are not used when CIEPS is used.

#### ACME challenge types

Vault supports the following ACME challenge types presently:

 - `http-01`, supporting both `dns` and `ip` identifiers.
 - `dns-01`, supporting `dns` identifiers including wildcards.
 - `tls-alpn-01`, supporting only non-wildcard `dns` identifiers.

A custom DNS resolver used by the server for looking up DNS names for use
with both mechanisms can be added via the [ACME configuration](#set-acme-configuration).

#### ACME external account bindings

ACME External Account Binding (EAB) Policy can enforce that clients need to
have a valid external account binding to Vault. Before registering a new account,
an authenticated Vault client will need to [fetch a new EAB
token](#get-acme-eab-binding-token). This returns two values: a key identifier
and an HMAC key used by the ACME client to authenticate with EAB. For example:

```
$ vault write -f /pki/acme/new-eab
$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \
                   --eab-kid <id> --eab-hmac-key <hmac-key>
```

With or without EAB, requests from the ACME client are not authenticated using
traditional Vault authentication, but are instead authenticated through the
ACME protocol. With EAB however, a Vault authenticated client will have to
fetch an EAB token and pass it to the ACME client for use on the initial
registration: this binds the ACME client's registration to an authenticated
Vault endpoint, but not further to the client's entity or other information.

<Note title="Require EAB for public-facing Vault deployments">

We strongly recommend enabling EAB for public-facing Vault
deployments. Use the `VAULT_DISABLE_PUBLIC_ACME` environment
variable to force-enable EAB for all ACME instances.

</Note>

#### ACME accounts

ACME Accounts are created specific to a particular directory and are not
portable across Performance Secondary clusters.

#### ACME required headers

ACME requires the following response headers (`allowed_response_headers`)
to be specified by [mount tuning](/vault/api-docs/system/mounts#tune-mount-configuration):

 - `Replay-Nonce`
 - `Link`
 - `Location`

On an existing mount, these can be specified by running the following command:

```
$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \
                     -allowed-response-headers=Link \
                     pki/
```

### Get ACME EAB binding token

This endpoint returns a new ACME binding token. The `id` response field can
be used as the key identifier and the `key` response field be used as the
EAB HMAC key in the ACME Client.

Each call to this endpoint will generate and return a new EAB binding token
that is linked to the specific ACME directory it resides under. EAB tokens
are not usable across different ACME directories.

| Method | Path                                               |
|:-------|:---------------------------------------------------|
| `POST` | `/pki/acme/new-eab`                                |
| `POST` | `/pki/issuer/:issuer_ref/acme/new-eab`             |
| `POST` | `/pki/roles/:role/acme/new-eab`                    |
| `POST` | `/pki/issuer/:issuer_ref/roles/:role/acme/new-eab` |

#### Parameters

No parameters.

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/pki/acme/new-eab
```

#### Sample response

```
{
  "data": {
    "created_on": "2023-05-24T14:33:00-04:00",
    "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd",
    "key_type": "hs",
    "acme_directory": "acme/directory",
    "key": "MHcCAQE... additional data elided ...",
  }
}
```

### List unused ACME EAB binding tokens

This endpoint returns a list of all unused ACME binding tokens; once used,
they will be removed from this list.

| Method | Path       |
|:-------|:-----------|
| `LIST` | `/pki/eab` |

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/eab
```

#### Sample response

```
{
  "data": {
    "key_info": {
      "bc8088d9-3816-5177-ae8e-d8393265f7dd": {
        "created_on": "2023-05-24T14:33:00-04:00",
        "key_type": "hs",
        "acme_directory": "acme/directory"
      }
    },
    "keys": [
      "bc8088d9-3816-5177-ae8e-d8393265f7dd"
    ]
  }
}
```

### Delete unused ACME EAB binding tokens

This endpoint allows the deletion of an unused ACME binding token.

| Method   | Path               |
|:---------|:-------------------|
| `DELETE` | `/pki/eab/:key_id` |

#### Parameters

 - `key_id` `(string: <required>)` - The id of the EAB binding token to
   delete. This is part of the request URL.

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd
```

### Get ACME configuration

This endpoint allows reading of the current ACME server configuration used by
this mount.

| Method | Path               |
|:-------|:-------------------|
| `GET`  | `/pki/config/acme` |

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/acme
```

#### Sample response

```
{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true,
    "max_ttl": 776000
  },
}
```

### Set ACME configuration

This endpoint allows setting the ACME server configuration used by this
mount.

| Method | Path               |
|:-------|:-------------------|
| `POST` | `/pki/config/acme` |

#### Parameters

 - `allowed_issuers` `(list: ["*"])` - Specifies a list issuers allowed to
   issue certificates via explicit ACME paths. If an allowed role specifies
   an issuer outside this list, it will be allowed. The default value `*`
   allows every issuer within the mount.

  - `allow_role_ext_key_usage` `(bool: false)` - whether the ExtKeyUsage field
   from a role is used, defaults to false meaning that certificate will be
   signed with ServerAuth.

 - `allowed_roles` `(list: ["*"])` - Specifies a list of roles allowed to
   issue certificates via explicit ACME paths.  The default value `*` allows
   every role within the mount to be used.  If the `default_directory_policy`
   specifies a role, it must be allowed under this configuration.

 - `default_directory_policy` `(string: "sign-verbatim")` - Specifies the
   behavior of the default ACME directory.  Can be `forbid`, `sign-verbatim`
   or a role given by `role:<role_name>`.  If a role is used, it must be
   present in `allowed_roles`.

 - `dns_resolver` `(string: "")` - An optional overriding DNS resolver to
   use for challenge verification lookups. When not specified, the default
   system resolver will be used. This allows domains on peered networks with
   an accessible DNS resolver to be validated.

 - `eab_policy` `(string: "not-required")` - Specified policy to enforce
   around [External Account Bindings (EABs)](#acme-external-account-bindings).
   The allowed values are:

     - `not-required`, where EABs are not enforced but are validated if
        specified.

     - `new-account-required`, where new accounts are required to have EAB
       but existing accounts can still be used.

     - `always-required`, where all accounts regardless of age are required
       to have EABs set.

 - `enabled` `(bool: false)` - Whether ACME is enabled on this mount. When
   ACME is disabled, all requests to ACME directory URLs will return 404.

 - `max_ttl` `(string: "")` - Specifies the maximum Time To Live provided as a
   string duration with time suffix. Hour is the largest suffix. If not set,
   defaults to the previous hard-coded behavior of 90 days (2160 hours).

#### Sample payload

```
{
    "enabled": true
}
```

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/acme
```

#### Sample response

```
{
  "data": {
    "allowed_issuers": [
      "*"
    ],
    "allowed_roles": [
      "*"
    ],
    "default_directory_policy": "sign-verbatim",
    "dns_resolver": "",
    "eab_policy": "not-required",
    "enabled": true
  }
}
```

### List ACME account keys

The `ListAcmeAccountKeys` endpoint returns a list of ACME account key
identifiers.

| Method | Path                           |
|:-------|:-------------------------------|
| `LIST` | `/pki/acme/mgmt/account/keyid` |

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid
```

#### Sample response

```
{
  "data": {
    "keys": [
      "2ea9859a-eba8-ff24-cd03-2a51639fc7d5"
    ]
  }
}
```

### Get ACME account info

The `GetAcmeAccountInfo` endpoint returns account information,
including orders and certificate details, for the provided ACME account
key.

| Method | Path                                   |
|:-------|:---------------------------------------|
| `GET`  | `/pki/acme/mgmt/account/keyid/:key_id` |

#### Path parameters

- `key_id` `(string: <required>)` - ID of the target ACME account.

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5
```

#### Sample response

```
{
  "data": {
    "contacts": null,
    "created_time": "2024-12-12T12:55:50-05:00",
    "directory": "acme/",
    "eab": {
      "created_time": "2024-12-12T12:55:29-05:00",
      "directory": "acme/",
      "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
      "key_type": "hs"
    },
    "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
    "orders": [
      {
        "cert_expiry": "2024-12-13T17:55:28Z",
        "cert_serial_number": "4a:6f:d0:f7:13:55:f7:c9:19:82:fc:34:69:67:77:2e:58:27:02:8b",
        "identifiers": [
          "testing.dadgarcorp.com"
        ],
        "order_expiry": "2024-12-13T12:56:04-05:00",
        "order_id": "90699994-8863-571c-26b0-46755e0db351",
        "status": "valid"
      }
    ],
    "revoked_time": "",
    "status": "valid"
  },
}
```

### Update ACME account info

The `UpdateAcmeAccountInfo` endpoint revokes or re-enables an ACME
account and returns the account details excluding order or certificate
details.

| Method | Path                                   |
|:-------|:---------------------------------------|
| `POST` | `/pki/acme/mgmt/account/keyid/:key_id` |

#### Path parameters

- `key_id` `(string: <required>)` - ID of the target ACME account.


### Parameters

- `status` `(string: <required>)` - The new account status. Must be one of:
 `revoked`, `valid`.

<Note title="ACME account revocation does not revoke certificates">

Revoking an ACME account forbids further operations on the account
without revoking existing certificates. You must revoke any existing
certificates manually.

</Note>

#### Sample request

```
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5
```

#### Sample response

```
{
  "data": {
    "contacts": null,
    "created_time": "2024-12-12T12:55:50-05:00",
    "directory": "acme/",
    "eab": {
      "created_time": "2024-12-12T12:55:29-05:00",
      "directory": "acme/",
      "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c",
      "key_type": "hs"
    },
    "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5",
    "revoked_time": "2024-12-12T12:59:02-05:00",
    "status": "revoked"
  },
}
```

## EST Certificate issuance <EnterpriseAlert inline="true" />

Within Vault Enterprise, support can be enabled for the
[EST (Enrollment over Secure Transport) protocol](https://datatracker.ietf.org/doc/html/rfc7030)
for issuing and renewing leaf certificates.

### EST Protocol Paths <EnterpriseAlert inline="true" />

These are the EST protocol API paths currently supported from Vault's authentication
point of view. Note that the `cacerts` endpoint is unauthenticated.

@include 'pki-est-default-policy.mdx'

### Read EST Configuration <EnterpriseAlert inline="true" />

This endpoint fetches the current EST configuration.

| Method | Path              |
|:-------|:------------------|
| `GET`  | `/pki/config/est` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/est
```

#### Sample response

```json
{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "est-ca"
      },
      "userpass": {
        "accessor": "auth_userpass_2b333949"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enable_sentinel_parsing": true,
    "enabled": true,
    "label_to_path_policy": {
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}
```

### Set EST Configuration <EnterpriseAlert inline="true" />

This endpoint will update EST related configuration, returning the
updated values as a response along with an updated `last_updated` field.

| Method | Path              |
|:-------|:------------------|
| `POST` | `/pki/config/est` |

#### Parameters

- `enabled` `(bool: false)` - Specifies whether EST is enabled or not.

- `default_mount` `(bool: false)` - Should this mount register the default .well-known/est URL path.
  Only a single mount can enable this across a Vault cluster

- `default_path_policy` `(string: "")` - Required to be set if `default_mount` is enabled. Specifies the
  behavior for requests using the default EST label. Can be `sign-verbatim` or a role given by `role:<role_name>`.

- `label_to_path_policy` `(map[string]string: "")` - Configures a pairing of an EST label with the redirected
 behavior for requests hitting that role. The path policy can be `sign-verbatim` or a role given by `role:<role_name>`.
 Labels must be unique across Vault cluster, and will register `.well-known/est/<label>` URL paths.

- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount accessors EST should delegate authentication
 requests. Map keys can be either `cert` or `userpass`, with associated maps containing the key `accessor` with a value
 containing the auth mount's accessor. For the `cert` type, an optional key `cert_role` parameter is supported which
 will be passed as the [name](/vault/api-docs/auth/cert#name-6) parameter during certificate authentication attempts.

- `enable_sentinel_parsing` `(bool: false)` - Parse out fields from the provided CSR making them available for
 Sentinel policies.

- `audit_fields` `(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])` - Fields parsed from the CSR that
 appear in the audit and can be used by sentinel policies. Allowed values are `csr`, `common_name`, `alt_names`,
 `ip_sans`, `uri_sans`, `other_sans`, `signature_bits`, `exclude_cn_from_sans`, `ou`, `organization`, `country`,
 `locality`, `province`, `street_address`, `postal_code`, `serial_number`, `use_pss`, `key_type`, `key_bits`,
 `add_basic_constraints`

#### Sample Payload

```json
{
  "enabled": true,
  "default_mount": true,
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
    "userpass": {
      "accessor": "auth_userpass_b2b08fac"
    }
  },
  "enable_sentinel_parsing": true,
  "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"]
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/est
```

#### Sample response

```json
{
  "data": {
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      },
      "userpass": {
        "accessor": "auth_userpass_b2b08fac"
      }
    },
    "default_mount": true,
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "label_to_path_policy": {
      "sign-all": "sign-verbatim",
      "test-label": "role:est-clients"
    },
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}
```


## CMPv2 Certificate issuance <EnterpriseAlert inline="true" />

Within Vault Enterprise, support can be enabled for the
[CMPv2 (Certificate Management Protocol) protocol](https://datatracker.ietf.org/doc/html/rfc4210)
for issuing and renewing leaf certificates.

### CMPv2 Protocol Paths <EnterpriseAlert inline="true" />

These are the CMP protocol API paths currently supported from Vault's authentication
point of view.

| Path                   | Default Path Policy | Issuer                | Role          |
|:-----------------------|:--------------------|:----------------------|:--------------|
| `/pki/cmp`             | `sign-verbatim`     | `default`             | Sign-Verbatim |
| `/pki/cmp`             | `role:role_ref`     | Specified by the role | `:role_ref`   |
| `/pki/roles/:role/cmp` | (any)               | Specified by the role | `:role`       |

The Default Path Policy is specified in the [CMPv2 configuration](#set-cmpv2-configuration).
When a role is not explicitly specified within the path, the behavior is specified by the `default_path_policy` field.

### Read CMPv2 Configuration <EnterpriseAlert inline="true" />

This endpoint fetches the current CMPv2 configuration.

| Method | Path              |
|:-------|:------------------|
| `GET`  | `/pki/config/cmp` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/cmp
```

#### Sample response

```json
{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "default_path_policy": "role:example-role",
    "disabled_validations": [],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_7fe0c1cc",
        "cert_role": "cmp-ca"
      }
    },
    "enable_sentinel_parsing": true,
    "enabled": true,
    "last_updated": "2024-01-31T10:45:22-05:00"
  }
}
```

### Set CMPv2 Configuration <EnterpriseAlert inline="true" />

This endpoint will update CMPv2 related configuration, returning the
updated values as a response along with an updated `last_updated` field.

| Method | Path              |
|:-------|:------------------|
| `POST` | `/pki/config/cmp` |

#### Parameters

- `enabled` `(bool: false)` - Specifies whether CMPv2 is enabled or not.

- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount accessors CMPv2 should delegate authentication
 requests. Map key can only be `cert`, with associated value containing the key `accessor` with a value
 containing the auth mount's accessor. An optional key `cert_role` parameter is supported which
 will be passed as the [name](/vault/api-docs/auth/cert#name-6) parameter during certificate authentication attempts.

- `default_path_policy` `(string: required)`: Specify the default issuance policy
  when the non role based cmp path is called.  Must be set to either `sign-verbatim`
  (to issue via the sign-verbatim function) or `role:` followed by the name of a configured
  role.

- `enable_sentinel_parsing` `(bool: false)` - Parse out fields from the provided CSR making them available for
 Sentinel policies.

- `audit_fields` `(list: ["common_name", "alt_names", "ip_sans", "uri_sans"])` - Fields parsed from the CSR that
 appear in the audit and can be used by sentinel policies. Allowed values are `csr`, `common_name`, `alt_names`,
 `ip_sans`, `uri_sans`, `other_sans`, `signature_bits`, `exclude_cn_from_sans`, `ou`, `organization`, `country`,
 `locality`, `province`, `street_address`, `postal_code`, `serial_number`, `use_pss`, `key_type`, `key_bits`,
 `add_basic_constraints`

- `disabled_validations` `(list: [])` - Checks to skip during request validation. Possible values are
 `DisableMatchingKeyIdValidation`, and 'DisableCertTimeValidation'. `DisableMatchingKeyIdValidation` disables
 the check that sender key ID in the request header needs to match the subject public key ID in the signing
 certificate. `DisableCertTimeValidation` disables the not before/not after verifications within the signing
 certificate. Disabling any validation is highly discouraged.

#### Sample Payload

```json
{
  "enabled": true,
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_0f1df449",
      "cert_role": "cert1"
    },
   "default_path_policy": "sign-verbatim",
   "disabled_validations": ["DisableMatchingKeyIdValidation"],
   "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
   "enable_sentinel_parsing": true
  }
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/pki/config/cmp
```

#### Sample response

```json
{
  "data": {
    "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_0f1df449",
        "cert_role": "cert1"
      }
    },
    "default_path_policy": "sign-verbatim",
    "disabled_validations": ["DisableMatchingKeyIdValidation"],
    "enabled": true,
    "enable_sentinel_parsing": true,
    "last_updated": "2024-02-02T10:49:20-05:00"
  }
}
```

## SCEP certificate issuance <EnterpriseAlert inline="true" />

Vault Enterprise supports
[SCEP (Simple Certificate Enrollment Protocol)](https://datatracker.ietf.org/doc/html/rfc8894)
when issuing leaf certificates.

For a comprehensive overview of SCEP and how to configure it,
refer to the [SCEP documentation](/vault/docs/secrets/pki/scep).

### SCEP protocol paths <EnterpriseAlert inline="true" />

Vault authentication supports the following SCEP protocol paths:

| Path                    | Default Path Policy | Issuer                | Role          |
|:------------------------|:--------------------|:----------------------|:--------------|
| `/pki/scep`             | `sign-verbatim`     | `default`             | Sign-Verbatim |
| `/pki/scep`             | `role:role_ref`     | Specified by the role | `:role_ref`   |
| `/pki/roles/:role/scep` | (any)               | Specified by the role | `:role`       |

### Read SCEP configuration <EnterpriseAlert inline="true" />

Fetch the current SCEP configured for PKI.

| Method | Path               |
|:-------|:-------------------|
| `GET`  | `/pki/config/scep` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/pki/config/scep
```

#### Sample response

```json
{
  "data": {
    "allowed_digest_algorithms": [
      "sha-256",
      "sha-384",
      "sha-512"
    ],
    "allowed_encryption_algorithms": [
      "aes128-cbc",
      "aes128-gcm",
      "aes256-cbc",
      "aes256-gcm"
    ],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_598b1030",
        "cert_role": "scep-ca"
      },
      "scep": {
        "accessor": "auth_scep_797d8401",
        "scep_role": ""
      }
    },
    "default_path_policy": "sign-verbatim",
    "enabled": true,
    "external_validation": {},
    "last_updated": "2025-05-26T09:59:24-04:00",
    "restrict_ca_chain_to_issuer": true
  }
}
```

### Set SCEP configuration <EnterpriseAlert inline="true" />

Update SCEP related configuration for your PKI plugin. On success, Vault updates
the `last_updated` field and returns the new configuration values.
For a comprehensive overview of SCEP and how to configure it,
refer to the [SCEP documentation](/vault/docs/secrets/pki/scep).

| Method | Path               |
|:-------|:-------------------|
| `POST` | `/pki/config/scep` |

#### Parameters

- `enabled` `(bool: false)` - Specifies whether SCEP is enabled or not.

- `default_path_policy` `(string: "")` - Specifies the behavior for
  non-role-qualified SCEP requests. Must be a role given by `role:<role_name>`
  or `sign-verbatim`.

- `authenticators` `(map[string]map[string]string: "")` - Specifies the mount
  accessors to which SCEP should delegate authentication requests. Map keys can
  be any of the following:

    - `scep` - Associated value is a map containing configuration details for
      SCEP authentication. Associated subkeys:
      - `accessor` (required) - mount path for the authentication plugin.
      - `scep_role` (optional) - the
        [`name`](/vault/api-docs/auth/scep#name) parameter passed during SCEP
        authentication attempts.

    - `cert` - Associated value is a map containing configuration details for
      certificate based authentication. Associated subkeys:
      - `accessor` (required) - mount path for the authentication plugin.
      - `cert_role` (optional) - the
        [`name`](/vault/api-docs/auth/cert#name-6) parameter passed during
        certificate authentication attempts.

- `allowed_encryption_algorithms` `([]string)` - the list of allowed encryption
  algorithms for SCEP requests. Can be any of:
    - `des-cbc` - DES encryption in CBC mode
    - `3des-cbc` - 3DES encryption in CBC mode
    - `aes128-cbc` - AES-128 encryption in CBC mode
    - `aes256-cbc` - AES-256 encryption in CBC mode
    - `aes128-gcm` - AES-128 encryption in GCM mode
    - `aes256-gcm` - AES-256 encryption in GCM mode

- `allowed_digest_algorithms` `([]string)` - the list of allowed digest algorithms for SCEP requests.  May be any of: `sha-1`, `sha-256`, `sha-384`, `sha-512`

- `restrict_ca_chain_to_issuer` `(bool: false)` - whether to return the full CA
  chain within GetCACert responses. Set `restrict_ca_chain_to_issuer` to `true`
  to make your PKI configuration compatible with Microsoft Intune.

- `external_validation` `(map[string]map[string]string: "")` - a map specifying
  configuration for 3rd party validation of SCEP requests. Map keys can
	be any of the following:
    - `intune` - Associated value is a map containing configuration details to
      validate authentication requests with Microsoft Intune. Associated
      subkeys:
    
      - `tenant_id` `(string: <required>)` - Tenant ID for the Azure Active
        Directory organization. Overrides the `AZURE_TENANT_ID` environment
        variable.
      - `client_id` `(string: <required or "MSI">)` - Client ID for credentials
        used to invoke Azure APIs. Overrides the `AZURE_CLIENT_ID` environment
        variable.
      - `client_secret` `(string: <required or "MSI">)` - Client secret for
        credentials to invoke Azure APIs.. Overrides the `AZURE_CLIENT_SECRET`
        environment variable.
      - `environment` `(string: "AzurePublicCloud")` - Azure Cloud environment
        API endpoints to use for validation. Overrides the `AZURE_ENVIRONMENT`
        environment variable.

    All `intune` parameter values can use
    [indirect value reference](/vault/docs/configuration/seal#indirect-value-references).

#### Sample Payload

```json
{
  "enabled": true,
  "default_path_policy": "role:scep-clients",
  "authenticators": {
    "scep": {
      "accessor": "auth_scep_797d8401"
    },
    "cert": {
      "accessor": "auth_cert_598b1030",
      "cert_role": "scep-ca"
    }
  }
}
```


#### Sample response

```json
{
  "data": {
    "allowed_digest_algorithms": [
      "sha-256",
      "sha-384",
      "sha-512"
    ],
    "allowed_encryption_algorithms": [
      "aes128-cbc",
      "aes128-gcm",
      "aes256-cbc",
      "aes256-gcm"
    ],
    "authenticators": {
      "cert": {
        "accessor": "auth_cert_598b1030",
        "cert_role": "scep-ca"
      },
      "scep": {
        "accessor": "auth_scep_797d8401",
        "scep_role": ""
      }
    },
    "default_path_policy": "role:scep-clients",
    "enabled": true,
    "external_validation": {},
    "last_updated": "2025-05-26T09:59:24-04:00",
    "restrict_ca_chain_to_issuer": false
  }
}
```
